Push nến WS
URL kết nối:
wss://stream.valuescan.ai/stream/ws/openapi/kline
1. Tổng quan
Push nến WS cung cấp dữ liệu nến theo giây thời gian thực cho các token đã đăng ký. Sau khi client thiết lập kết nối WebSocket và hoàn tất đăng ký, client sẽ nhận tin nhắn nến cho các token đã đăng ký.
Đặc điểm chính:
- Push thời gian thực: Push thay đổi nến hiện tại, không chỉ nến đã đóng.
- Dữ liệu theo giây: Hiện chỉ push nến theo giây
bucketType=1s. - Đăng ký theo kết nối: Mỗi kết nối WS duy trì danh sách đăng ký riêng.
- Kết nối lại khi mất kết nối: Client phải kết nối lại và đăng ký lại sau khi mất kết nối.
Lưu ý: Nội dung push phản ánh thay đổi thị trường trực tiếp; không đảm bảo mỗi token nhận tin nhắn mỗi giây. Với 1m, 5m, 1h và các chu kỳ khác, hãy tổng hợp từ dữ liệu theo giây nhận được trên client.
2. URL kết nối
GET wss://stream.valuescan.ai/stream/ws/openapi/kline3. Xác thực
Nến WS xác thực khi thiết lập kết nối. Tham số được truyền trong Query String.
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
apiKey | string | Có | ValueScan Access Key |
sign | string | Có | Chữ ký HMAC-SHA256 |
timestamp | long | Có | Unix timestamp đơn vị mili giây |
nonce | string | Có | Chuỗi ngẫu nhiên (chống replay) |
Thuật toán ký:
sign = HMAC-SHA256(SK, timestamp毫秒 + nonce)Ví dụ:
import hashlib
import hmac
import time
import uuid
AK = "your-access-key"
SK = "your-secret-key"
timestamp = str(int(time.time() * 1000))
nonce = uuid.uuid4().hex
sign = hmac.new(
SK.encode(),
(timestamp + nonce).encode(),
hashlib.sha256,
).hexdigest()4. Credits consumption
- Billing: Tính phí theo người dùng; 100 Credits mỗi 30 phút khi kết nối WS đang hoạt động.
- Credits không đủ: Kết nối nhận thông báo lỗi chuẩn và ngắt kết nối.
Trong chu kỳ tính phí 30 phút đã trừ thành công, kết nối vẫn sử dụng được; nếu Credits không đủ ở chu kỳ tiếp theo, kết nối sẽ đóng.
5. Định dạng kết nối và tin nhắn
1. Kết nối thành công
Sau khi kết nối được thiết lập và xác thực:
{
"type": "connected",
"payload": {
"requestId": "7b8a0b7f9f4a4f2c91f9e1e48c36d5b2"
}
}2. Đăng ký
Client gửi:
{
"type": "subscribe",
"payload": {
"items": [
{
"vsTokenId": 1
}
]
}
}Xác nhận đăng ký:
{
"type": "subscribed",
"payload": {
"items": [
{
"vsTokenId": 1
}
]
}
}3. Hủy đăng ký
Hủy token cụ thể:
{
"type": "unsubscribe",
"payload": {
"items": [
{
"vsTokenId": 1
}
]
}
}Hủy toàn bộ đăng ký trên kết nối hiện tại:
{
"type": "unsubscribe",
"payload": {}
}Xác nhận hủy đăng ký:
{
"type": "unsubscribed",
"payload": {
"items": []
}
}4. Push nến
Tin nhắn nến:
{
"type": "data",
"payload": {
"vsTokenId": 1,
"bucketType": "1s",
"tradePair": "BTCUSDT",
"klineType": "01",
"time": 1781686187000,
"open": 64873.11,
"close": 64877.29,
"high": 64877.3,
"low": 64873.11,
"volume": 0.27783,
"value": 18023.8032114,
"uniqueId": "01:BTCUSDT:1781686187000:1s"
}
}Các trường payload:
| Trường | Kiểu | Mô tả |
|---|---|---|
vsTokenId | long | ID token |
bucketType | string | Cửa sổ thời gian nến; cố định 1s |
tradePair | string | Cặp giao dịch USDT mặc định |
klineType | string | Loại nguồn nến; xem enum KlineType |
time | long | Thời gian nến (timestamp mili giây) |
open | number | Giá mở cửa |
close | number | Giá đóng cửa |
high | number | Giá cao nhất |
low | number | Giá thấp nhất |
volume | number | Khối lượng |
value | number | Giá trị giao dịch |
uniqueId | string | ID push duy nhất để khử trùng lặp trên client |
6. Giới hạn đăng ký
| Giới hạn | Tối đa | Mô tả |
|---|---|---|
| Kết nối nến WS mỗi người dùng | 50 | Vượt quá trả về lỗi giới hạn tốc độ |
| Token mỗi kết nối WS | 200 vsTokenId | vsTokenId trùng lặp chỉ tính một lần |
Chia đăng ký sang nhiều kết nối khi gần đạt 200 token mỗi kết nối.
7. Thông báo lỗi
Lỗi nghiệp vụ sau khi kết nối WS dùng JSON thống nhất:
{
"type": "error",
"payload": {
"code": 40001,
"message": "Required parameter is missing",
"requestId": "a7d7ce3053e140dca91d93df173648f8"
}
}Mã lỗi phổ biến:
| code | Mô tả |
|---|---|
20001 | Thiếu API Key |
20012 | Timestamp hết hạn |
20021 | Xác thực chữ ký thất bại |
40001 | Thiếu tham số bắt buộc, ví dụ mục đăng ký thiếu vsTokenId |
40002 | Định dạng hoặc giá trị tham số không hợp lệ |
60001 | Giới hạn tốc độ, ví dụ vượt số kết nối hoặc đăng ký |
70001 | OpenApi Credits không đủ |
Lỗi xác thực khi thiết lập kết nối trả về HTTP 200 với JSON nghiệp vụ; code trong body cho biết lỗi thực tế.
8. Ví dụ tích hợp
Python
Phụ thuộc:
pip install websocket-clientVí dụ:
import hashlib
import hmac
import json
import time
import uuid
import urllib.parse
import websocket
AK = "your-access-key"
SK = "your-secret-key"
VS_TOKEN_ID = 1
timestamp = str(int(time.time() * 1000))
nonce = uuid.uuid4().hex
sign = hmac.new(
SK.encode(),
(timestamp + nonce).encode(),
hashlib.sha256,
).hexdigest()
params = urllib.parse.urlencode({
"apiKey": AK,
"sign": sign,
"timestamp": timestamp,
"nonce": nonce,
})
url = f"wss://stream.valuescan.ai/stream/ws/openapi/kline?{params}"
ws = websocket.create_connection(url, timeout=10)
try:
connected = json.loads(ws.recv())
print("connected:", connected)
ws.send(json.dumps({
"type": "subscribe",
"payload": {
"items": [
{"vsTokenId": VS_TOKEN_ID}
]
}
}))
while True:
message = json.loads(ws.recv())
msg_type = message.get("type")
if msg_type == "subscribed":
print("subscribed:", message)
elif msg_type == "data":
kline = message["payload"]
print(
f"[{kline['tradePair']}] "
f"time={kline['time']} close={kline['close']} volume={kline['volume']}"
)
elif msg_type == "error":
print("error:", message)
break
finally:
ws.close()9. Khuyến nghị kết nối lại
Kết nối nến WS có thể bị ngắt do mạng, bảo trì hoặc Credits không đủ. Hành vi client khuyến nghị:
- Lắng nghe sự kiện đóng kết nối.
- Kết nối lại với backoff theo cấp số nhân; tránh thử lại quá dày.
- Tạo lại
timestamp,noncevàsignkhi kết nối lại. - Gửi lại tin nhắn đăng ký để khôi phục danh sách.
- Dùng
uniqueIdđể khử trùng lặp idempotent cho tin nhắn nến đã xử lý.
Ví dụ khoảng backoff: 1s, 2s, 4s, 8s, tối đa 60s.